---
overviewHeaders: [2, 3]
---

# lib.dts

- **类型：**

```ts
type Dts =
  | {
      bundle?: boolean;
      distPath?: string;
      build?: boolean;
      abortOnError?: boolean;
      autoExtension?: boolean;
    }
  | boolean;
```

- **默认值：** `undefined`

配置 TypeScript 声明文件的生成。

## 布尔类型

类型声明文件生成是一个可选功能，你可以设置 `dts: true` 来启用 [bundleless 类型](/guide/advanced/dts#bundleless-类型) 生成。

```ts title="rslib.config.ts" {5}
export default {
  lib: [
    {
      format: 'esm',
      dts: true,
    },
  ],
};
```

如果你想要禁用类型声明文件生成，可以设置 `dts: false` 或者不指定 `dts` 选项。

```ts title="rslib.config.ts" {5}
export default {
  lib: [
    {
      format: 'esm',
      dts: false,
    },
  ],
};
```

## 对象类型

如果你想要自定义类型声明文件的生成，可以将 `dts` 选项设置为一个对象。

### dts.bundle

- **类型：** `boolean`
- **默认值：** `false`

是否打包类型声明文件。

#### 示例

如果你想要 [bundle 类型](/guide/advanced/dts#bundle-类型)，你需要：

1. 安装 [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) 作为开发依赖，它是用于打包类型声明文件的底层工具。

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @microsoft/api-extractor -D" />

2. 将 `dts.bundle` 设置为 `true`。

```ts title="rslib.config.ts" {5-7}
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        bundle: true,
      },
    },
  ],
};
```

#### 处理第三方依赖

当我们打包类型声明文件时，我们需要指定哪些第三方包的类型需要被打包，可以参考 [处理第三方依赖](/guide/advanced/third-party-deps) 文档了解更多关于 externals 相关的配置。

### dts.distPath

- **类型：** `string`

类型声明文件的输出目录。

#### 默认值

默认值按照以下优先级确定：

1. 当前 lib 配置中的 `dts.distPath` 值。
2. `tsconfig.json` 文件中的 `declarationDir` 值。
3. 当前 lib 配置中的 [output.distPath.root](/config/rsbuild/output#outputdistpath) 值。

#### 示例

```ts title="rslib.config.ts" {5-7}
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        distPath: './dist-types',
      },
    },
  ],
};
```

### dts.build

- **类型：** `boolean`
- **默认值：** `false`

是否在生成类型声明文件时构建项目的 references。这相当于在 `tsc` 命令中使用 `--build` 标志。更多详细信息请参考 [项目引用](https://www.typescriptlang.org/docs/handbook/project-references.html)。

::: note

当启用此选项时，你必须在 `tsconfig.json` 中显式设置 `declarationDir` 或 `outDir` 以满足构建要求。

:::

### dts.abortOnError

- **类型：** `boolean`
- **默认值：** `true`

当类型声明文件生成过程中出现错误时，是否中止构建过程。

默认情况下，类型错误会导致构建失败。

当 `abortOnError` 设置为 `false` 时（如下所示），即使代码中存在类型问题，构建仍然会成功。

```ts title="rslib.config.ts" {5-7}
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        abortOnError: false,
      },
    },
  ],
};
```

::: warning

当禁用该配置时，无法保证类型文件会被正确生成。

:::

### dts.autoExtension

- **类型：** `boolean`
- **默认值：** `false`

是否根据 [format](/config/lib/format) 选项自动设置类型声明文件扩展名。

#### 默认扩展名

当 `dts.autoExtension` 为 `false` 时，类型声明文件扩展名默认为 `.d.ts`。

当 `dts.autoExtension` 设置为 `true` 时，类型声明文件扩展名将会是：

- 当 `package.json` 中设置 `type: module` 时，`esm` 格式使用 `.d.ts`，`cjs` 格式使用 `.d.cts`。

- 当 `package.json` 中设置 `type: commonjs` 或没有 `type` 字段时，`cjs` 格式使用 `.d.ts`，`esm` 格式使用 `.d.mts`。

::: note

这遵循与 [lib.autoExtension](/config/lib/auto-extension) 相同的逻辑，但默认值不同，因为类型声明文件扩展名可能会在不同的模块解析策略中造成一些问题。

:::
